/**
 * @file lcd.h
 * @brief LCD屏幕绘图功能模块的头文件
 * @details 声明了用于在LCD上进行底层绘图操作（如画点、填充、显示图像）
 * 所需的全局变量和函数原型。
 * @version 1.0
 * @date 2025-07-05
 */

#ifndef _LCD_DRAWING_H_
#define _LCD_DRAWING_H_


/**
 * @brief 外部声明：指向LCD显存映射区域的指针。
 * @details 假设每个像素点为32位 (4字节) ARGB 格式。
 * 该指针应在初始化阶段被赋值。
 */
extern unsigned int *plcd;


// --- 函数原型声明 ---

/**
 * @brief 在LCD屏幕的指定坐标绘制一个像素点。
 * @param x     像素点的X坐标。
 * @param y     像素点的Y坐标。
 * @param color 像素点的32位颜色值 (如 0x00RRGGBB)。
 */
void draw_point(int x, int y, int color);

/**
 * @brief 使用单一颜色填充整个LCD屏幕。
 * @param color 用于填充的32位颜色值。
 */
void brush_lcd(int color);

/**
 * @brief 从内存缓冲区绘制一张原始24位RGB图像。
 * @param image 包含像素数据的缓冲区。
 * @param wide  图像的宽度。
 * @param high  图像的高度。
 * @param x1    绘制区域左上角的X坐标。
 * @param y1    绘制区域左上角的Y坐标。
 */
void draw_image(const unsigned char image[], int wide, int high, int x1, int y1);

/**
 * @brief 在LCD的指定位置绘制一个BMP图像。
 * @param bmpfile   BMP图像文件的路径。
 * @param x0        绘制区域左上角的X坐标。
 * @param y0        绘制区域左上角的Y坐标。
 * @return int      成功返回0, 失败返回-1。
 */
int draw_bmp(const char*bmpfile, int x0, int y0);

/**
 * @brief 使用libjpeg解码并绘制一个JPEG图像。
 * @param jpegfile JPEG图像文件的路径。
 * @param x0       绘制区域左上角的X坐标。
 * @param y0       绘制区域左上角的Y坐标。
 */
void draw_jpeg(const char*jpegfile, int x0, int y0);

/**
 * @brief 在指定位置绘制一个8x16的单色字符或图案。
 * @param x0    字符左上角的X坐标。
 * @param y0    字符左上角的Y坐标。
 * @param buf   包含16字节点阵数据的缓冲区。
 * @param color 字符的32位颜色值。
 */
void draw_8x16(int x0, int y0, unsigned char buf[], int color);

/**
 * @brief 在指定位置绘制一个16x16的单色字符或图案 (如汉字)。
 * @param x0    字符左上角的X坐标。
 * @param y0    字符左上角的Y坐标。
 * @param buf   包含32字节点阵数据的缓冲区。
 * @param color 字符的32位颜色值。
 */
void draw_16x16(int x0, int y0, unsigned char buf[], int color);

/**
 * @brief 解码JPEG并按比例缩放后居中绘制到“视口”内。
 * @param jpegfile      JPEG图像文件的路径。
 * @param scale         缩放比例 (e.g., 0.5)。
 * @param viewport_x    视口左上角X坐标。
 * @param viewport_y    视口左上角Y坐标。
 * @param viewport_w    视口宽度。
 * @param viewport_h    视口高度。
 */
void draw_jpeg_with_scale(const char *jpegfile, double scale, int pan_offset_x, int pan_offset_y, int viewport_x, int viewport_y, int viewport_w, int viewport_h);

/**
 * @brief 读取BMP并按比例缩放后居中绘制到“视口”内。
 * @param bmpfile       BMP图像文件的路径。
 * @param scale         缩放比例。
 * @param viewport_x    视口左上角X坐标。
 * @param viewport_y    视口左上角Y坐标。
 * @param viewport_w    视口宽度。
 * @param viewport_h    视口高度。
 */
void draw_bmp_with_scale(const char *bmpfile, double scale, int pan_offset_x, int pan_offset_y, int viewport_x, int viewport_y, int viewport_w, int viewport_h);

/**
 * @brief 在指定位置绘制一个实心矩形。
 * @param x         矩形左上角的X坐标。
 * @param y         矩形左上角的Y坐标。
 * @param width     矩形的宽度。
 * @param height    矩形的高度。
 * @param color     矩形的填充颜色。
 */
void lcd_draw_rect(int x, int y, int width, int height, int color);


#endif // _LCD_H_